Inside Macintosh: Imaging with QuickDraw
Previous | Chapter Top | Chapter Contents | Next |
This section shows the Pascal data structures for the Picture , OpenCPicParams , CommentSpec , FontSpec , and PictInfo records.
When you use the OpenCPicture or OpenPicture function, QuickDraw begins collecting your subsequent drawing commands in a Picture record. When you use the GetPicture function to retrieve a picture stored in a resource, GetPicture reads the resource into memory as a Picture record.
When you use the OpenCPicture function to begin creating a picture, you must pass it information in an OpenCPicParams record. This record provides a simple mechanism for specifying resolutions when creating images.
When you use the GetPictInfo function, it returns information in a PictInfo record. When you gather this information for multiple pictures, pixel maps, or bitmaps, the RetrievePictInfo function also returns a PictInfo record containing this information.
If you specify the recordComments constant in the verb parameter to the GetPictInfo function or NewPictInfo function, your application receives a PictInfo record that includes a handle to a CommentSpec record. A CommentSpec record contains information about the comments in a picture.
If you specify the recordFontInfo constant in the verb parameter to the GetPictInfo function or NewPictInfo function, the function returns a PictInfo record that includes a handle to a FontSpec record. A FontSpec record contains information about the fonts in a picture.
When you use the OpenCPicture or OpenPicture function (described on OpenCPicture and OpenPicture , respectively), QuickDraw begins collecting your subsequent drawing commands in a Picture record. (You use the ClosePicture procedure, described on ClosePicture , to complete a picture definition.) When you use the GetPicture function (described on GetPicture ) to retrieve a picture stored in a resource, GetPicture reads the resource into memory as a Picture record. ( 'PICT' resources are described on The Picture Resource .) By using the DrawPicture procedure (described on DrawPicture ), you can draw onscreen the picture defined by the commands stored in the Picture record.
A Picture record is defined as follows:
TYPE Picture =
RECORD
picSize: Integer; {for a version 1 picture: its size}
picFrame: Rect; {bounding rectangle for the picture}
{variable amount of picture data in the form of opcodes}
END;
Picture comments and compact drawing instructions in the form of picture opcodes compose the rest of this record.
A picture opcode is a number that the DrawPicture procedure uses to determine what object to draw or what mode to change for subsequent drawing. For debugging purposes, picture opcodes are listed in Appendix A at the back of this book. Your application generally should not read or write this picture data directly. Instead, your application should use the OpenCPicture (or OpenPicture ), ClosePicture , and DrawPicture routines to process these opcodes.
The Picture record can also contain picture comments. Created by applications using the PicComment procedure, picture comments contain data or commands for special processing by output devices, such as PostScript printers. The PicComment procedure is described on PicComment , and picture comments are described in greater detail in Appendix B in this book.
You can use File Manager routines to save the picture in a file of type 'PICT' , you can use Resource Manager routines to save the picture in a resource of type 'PICT' , and you can use the Scrap Manager procedure PutScrap to store the picture in 'PICT' scrap format. See the chapter "File Manager" in Inside Macintosh: Files and the chapters "Resource Manager" and "Scrap Manager" in Inside Macintosh: More Macintosh Toolbox for more information about saving files, resources, and scrap data .
When you use the OpenCPicture function (described on OpenCPicture ) to begin creating a picture, you must pass it information in an OpenCPicParams record. This record provides a simple mechanism for specifying resolutions when creating images. For example, applications that create pictures from scanned images can specify resolutions higher than 72 dpi for these pictures in OpenCPicParams records.
An OpenCPicParams record is defined as follows:
TYPE OpenCPicParams =
RECORD
srcRect: Rect; {optimal bounding rectangle for }
{ displaying picture at resolution }
{ indicated in hRes, vRes fields}
hRes: Fixed; {best horizontal resolution; }
{ $00480000 specifies 72 dpi}
vRes: Fixed; {best vertical resolution; }
{ $00480000 specifies 72 dpi}
version: Integer; {set to -2}
reserved1: Integer; {reserved; set to 0}
reserved2: LongInt; {reserved; set to 0}
END;
If you specify the recordComments constant in the verb parameter to the GetPictInfo function (described on GetPictInfo ) or the NewPictInfo function (described on NewPictInfo ), you receive a PictInfo record (described beginning on PictInfo ) that includes in its commentHandle field a handle to an array of CommentSpec records. The uniqueComments field of the PictInfo record indicates the number of CommentSpec records in this array.
The CommentSpec record is defined as follows:
TYPE CommentSpec = {comment specification record}
RECORD
count: Integer; {number of times this type of comment }
{ occurs in the picture or survey}
ID: Integer; {value identifying this type of comment}
END;
When you are finished using the information returned in a CommentSpec record, you should use the DisposeHandle procedure (described in Inside Macintosh: Memory ) to dispose of the memory allocated to it.
Listing 7-12 illustrates how to count the number of picture comments by examining a CommentSpec record.
If you specify the recordFontInfo constant in the verb parameter to the GetPictInfo function (described on GetPictInfo ) or the NewPictInfo function (described on NewPictInfo ), your application receives a PictInfo record (described beginning on PictInfo ) that includes in its fontHandle field a handle to an array of FontSpec records. The uniqueFonts field of the PictInfo record indicates the number of FontSpec records in this array. (For bitmap fonts, a font is a complete set of glyphs in one size, typeface, and style--for example, 12-point Geneva italic. For outline fonts, a font is a complete set of glyphs in one typeface and style--for example, Geneva italic.)
The FontSpec record is defined as follows:
TYPE FontSpec = {font specification record}
RECORD
pictFontID: Integer; {font ID as stored in the picture}
sysFontID: Integer; {font family ID}
size: ARRAY[0..3] OF LongInt;
{each bit set from 1 to 127 indicates a }
{ point size at that value; if bit 0 is }
{ set, then a size larger than 127 }
{ points is found}
style: Integer; {styles used for this font family}
nameOffset: LongInt; {offset to font name stored in the }
{ data structure indicated by the }
{ fontNamesHandle field of the PictInfo }
{ record}
END;
TYPE
StyleItem = (bold, italic, underline, outline,
shadow, condense, extend);
Style = SET OF StyleItem;
When you are finished using the information returned in a FontSpec record, you should use the DisposeHandle procedure (described in Inside Macintosh: Memory ) to dispose of the memory allocated to it.
See the chapter "Font Manager" in Inside Macintosh: Text for more information about fonts.
When you use the GetPictInfo function (described on GetPictInfo ) to collect information about a picture, or when you use the GetPixMapInfo function (described on GetPixMapInfo ) to collect color information about a pixel map or bitmap, the function returns the information in a PictInfo record. When you gather this information for multiple pictures, pixel maps, or bitmaps, the RetrievePictInfo function (described on RetrievePictInfo ) also returns a PictInfo record containing this information.
Initially, all of the fields in a new PictInfo record are set to NIL . Relevant fields are set to appropriate values depending on the information you request using the Picture Utilities functions as described in this chapter.
The PictInfo record is defined as follows:
TYPE PictInfo =
RECORD
version: Integer; {Picture Utilities version number}
uniqueColors: LongInt; {total colors in survey}
thePalette: PaletteHandle; {handle to a Palette record--NIL for }
{ a bitmap in a basic graphics port}
theColorTable: CTabHandle; {handle to a ColorTable record--NIL }
{ for a bitmap in a basic graphics }
{ port}
hRes: Fixed; {best horizontal resolution (dpi)}
vRes: Fixed; {best vertical resolution (dpi)}
depth: Integer; {greatest pixel depth}
sourceRect: Rect; {optimal bounding rectangle for }
{ picture for display at resolution }
{ specified in hRes and vRes fields}
textCount: LongInt; {number of text strings in picture(s)}
lineCount: LongInt; {number of lines in picture(s)}
rectCount: LongInt; {number of rectangles in picture(s)}
rRectCount: LongInt; {number of rounded rectangles in }
{ picture(s)}
ovalCount: LongInt; {number of ovals in picture(s)}
arcCount: LongInt; {number of arcs and wedges in }
{ picture(s)}
polyCount: LongInt; {number of polygons in picture(s)}
regionCount: LongInt; {number of regions in picture(s)}
bitMapCount: LongInt; {number of bitmaps}
pixMapCount: LongInt; {number of pixel maps}
commentCount: LongInt; {number of comments in picture(s)}
uniqueComments: LongInt; {number of different comments }
{ (by ID) in picture(s)}
commentHandle: CommentSpecHandle;{handle to an array of CommentSpec }
{ records for picture(s)}
uniqueFonts: LongInt; {number of fonts in picture(s)}
fontHandle: FontSpecHandle; {handle to an array of FontSpec }
{ records for picture(s)}
fontNamesHandle: Handle; {handle to list of font names for }
{ picture(s)}
reserved1: LongInt;
reserved2: LongInt;
END;
When you are finished with this information, be sure to dispose of it. You can dispose of Palette records by using the DisposePalette procedure (which is described in the chapter "Palette Manager" in Inside Macintosh: Advanced Color Imaging ). You can dispose of ColorTable records by using the DisposeCTable procedure (described in the chapter "Color QuickDraw" in this book). You can dispose of other allocations with the DisposeHandle procedure (described in Inside Macintosh: Memory ).